GeneDock Offical Python SDK手册

安装

相关资源：

1. github项目
2. SDK API文档：所有的接口，以及类的细节
3. PyPi主页

环境依赖

此版本的Python SDK适用于Python 2.6、2.7、3.3、3.4、3.5版本。首先请根据python官网的引导安装合适的Python版本。

安装好Python后：

• 在Linux Shell里验证Python版本

 $ python -V
 Python 2.7.10

上面的输出表明您已经成功安装了Python 2.7.10版本。

• Windows CMD环境下验证Python版本：

 C:\> python -V
 Python 2.7.10

上面的输出表明您已经成功安装了Python 2.7.10版本。如果提示“不是内部或外部命令”，请检查配置“环境变量”-“Path”，增加Python的安装路径。

安装SDK

• 安装

从GeneDock网站下载相应版本的SDK包，解压后进入目录，确认目录下有setup.py这个文件：

 python setup.py install

也可以从Pypi安装(以Linux系统为例）:

pip install gdpy

• 在虚拟环境中安装

virtualenv 是一个创建隔绝的Python环境的工具。如果因为python环境问题使得安装失败，或者执行程序失败，建议在虚拟环境中安装/执行程序，以linux系统为例:

# 安装 virtualenv
$ sudo pip install virtualenv
# 测试你的安装: 你应该得到像 15.1.0 之类的输出
$ virtualenv --version
# 创建一个虚拟环境: 虚拟环境的名字 (此例中是 my_project) 可以是任意的
$ virtualenv my_project
# 激活虚拟环境（此例中是 my_project), 并进入该环境
$ source my_project/bin/activate
# 提示符左侧显示当前虚拟环境的名字 (此例中是 my_project)，表示你已进入虚拟环境
# 在虚拟环境中安装 gdpy
(my_project)$ pip install gdpy
# 在虚拟环境中运行python脚本，就像在平常环境里一样操作
# 如果在虚拟环境中暂时完成了工作，则可以退出虚拟环境，切换到平常的环境
(my_project)$ deactivate
# 删除一个虚拟环境, 只需删除它的文件夹
$ rm -rf my_project

• 验证

  首先命令行输入python并回车，在Python环境下检查SDK的版本：

>>> import gdpy
>>> gdpy.__version__
'0.0.1'

上面的输出表明您已经成功安装了特定版本的Python SDK（这里以版本 0.0.1 为例）。

卸载SDK

建议通过pip卸载：

pip uninstall gdpy

初始化

SDK所有操作可在官网下载的SDK包内genedock-official-python-sdk/examples目录下找到对应的样例，如有需要可仿照样板命令进行使用。以下内容对这些命令进行了详细说明

gdpy是GeneDock服务的Python基类，它为调用者提供一些和GeneDock进行交互的接口，用于管理、操作工作流（Workflow）和任务（Task）等资源。使用Offical Python SDK发起请求，您需要初始化一个gdpy实例，并根据需要修改gdpy的默认配置项。

确定Endpoint

请先阅读API-Reference中关于服务入口说明的部分，了解目前GeneDock所有服务的入口地址。

目前GeneDock各个域（Region）的Endpoint如下：

Region	Endpoint
北京域	https://cn-beijing-api.genedock.com
深圳域	https://cn-shenzhen-api.genedock.com
青岛域	https://cn-qingdao-api.genedock.com

获取密钥

要使用GeneDock的API服务，您需要一个有效的Access Key（包括AccessKeyId和AccessKeySecret）用来进行签名认证。如何获取密钥请参考命令行客户端使用手册中获取access_key_id和access_key_secret的说明。

获取了AccessKeyId和AccessKeySecret之后，您便可以按照以下的步骤进行初始化。

新建GeneDockAuth

GeneDockAuth是用户和GeneDock API连接时所需要提供的鉴权凭证。使用gdpy进行初始化时需要利用GeneDockAuth, access_key_id 和 access_key_secret 生成一个auth对象：

# 请登录https://www.genedock.com查看accessKey

import gdpy
auth = gdpy.GeneDockAuth('access_key_id', 'access_key_secret')

创建gdpy操作实例

gdpy提供了Tasks, Workflows, Tools三种实例类型，分别对应针对任务，工作流和工具的操作。

# 创建gdpy实例
# res_account_name为需要访问的资源的所属账号，project_name为需要访问的资源的所属项目，默认为default
# Tasks实例，以北京域为例
task = gdpy.Tasks(auth, 'cn-beijing-api.genedock.com', 'res_account_name', 'project_name')

# Workflows实例，以北京域为例
workflow = gdpy.Workflows(auth, 'cn-beijing-api.genedock.com', 'res_account_name', 'project_name')

# Tools实例，以北京域为例
tool = gdpy.Tools(auth, 'cn-beijing-api.genedock.com', 'res_account_name', 'project_name') 

# Data实例，以北京域为例
data = gdpy.Data(auth, 'cn-beijing-api.genedock.com', 'public')

提示

gdpy可以并发使用

创建实例时，endpoint默认使用https协议，只有部分私有云可使用http协议，请指定url为http://, 如 http://cn-beijing-api.genedock.com

快速入门

请确认您已经熟悉GeneDock的基本概念，如工作流、任务等。本节您将看到如何快速使用Offical Python SDK，完成对工作流和任务的常见操作。

初始化gdpy

向GeneDock发送任一HTTP请求之前，必须先创建一个gdpy实例：

import gdpy

# 请登录https://www.genedock.com查看accessKey
auth = gdpy.GeneDockAuth('access_key_id', 'access_key_secret')

# endpoin以北京为例，其他region请根据实际情况填写
task = gdpy.Tasks(auth, 'cn-beijing-api.genedock.com', 'res_account_name', 'project_name')

workflow = gdpy.Workflows(auth, 'cn-beijing-api.genedock.com', 'res_account_name', 'project_name')

tool = gdpy.Tools(auth, 'cn-beijing-api.genedock.com', 'res_account_name', 'project_name') 

注意

所有操作的返回类型继承了requests类的返回类型。用户可按照requests的返回查看所需要的内容

Tool操作

CreateTool

以下的代码展示如何在默认project下新建一个Tool：

create_tool_result = tool.create_tool('tool_name', 1, 'new tool')

提示：

Tool的命名规范，请参见API-Reference CreateTool的说明。

新建的tool的status是unchecked，不可以被列出或使用。只有正确执行了PutTool操作以后，状态变成checked后，工具才可以被列出和使用。
默认版本号为1

PutTool

此接口用来创建和更新Tool的定义。以下的代码展示如何给新建的Tool添加定义：

put_tool_result = tool.put_tool('parameter_file')

提示：

需要提供一个yml格式的parameter_file配置文件，记录该tool的配置

如果和create_tool配合使用，请注意需要和配置文件中的tool_name保持一致

可按照 genedock-official-python-sdk/examples/tool_put.yml 为例

GetTool

以下的代码展示如何获取一个指定tool的信息：

# 如果不指定版本号，则返回一个包含所有版本的tool的数组
get_tool_result = tool.get_tool('tool_name', tool_version)
# 查看获取的tool的详情
print get_tool_result.response.text

ListTool

以下的代码展示如何列举某账号下的tool：

list_tool_result = tool.list_tools()
# 查看tool列表详情
print list_tool_result.tools
# 列出的tool的数量
print list_tool_result.count

提示：

只能列出状态为checked的工具

DeleteTool

以下的代码展示如何删除一个tool：

# 必须指定版本号
delete_tool_result = tool.delete_tool('tool_name', tool_version)

提示：

只能删除状态为checked或者unchecked的工具。

Workflow操作

CreateWorkflow

以下的代码展示如何默认在project下新建一个workflow：

create_workflow_result = workflow.create_workflow('workflow_name', 1, 'new workflow')

提示：

Workflow的命名规范，请参见API-Reference CreateWorkflow的说明

新建的workflow的status是unchecked，不可以被运行。只有正确执行了PutWorkflowDefinition操作以后，状态变成checked后，工作流才可以被运行。

PutWorkflow

此接口用来创建和更新workflow的定义。以下的代码展示如何给新建的workflow添加定义：

put_workflow_result = workflow.put_workflow('parameter_file')

提示：

需要提供一个yml格式的parameter_file配置文件，记录该workflow的配置

可按照 genedock-official-python-sdk/examples/workflow_put.yml 为例

GetWorkflow

此接口用来获取workflow的定义。以下代码展示如何获取指定workflow的定义：

# 如果不指定版本号，则返回一个包含所有版本的workflow的数组
get_workflow_result = workflow.get_workflow('workflow_name', workflow_version)
# 查看获取的workflow的详情
print get_workflow_result.response.text

GetExecutableWorkflow

此接口用来获取workflow的参数模版。以下代码展示如何获取指定workflow的参数模版：

get_excutable_workflow_result = workflow.get_exc_workflows('workflow_name', workflow_version)
# 查看workflow详情
print get_excutable_workflow_result.response.text

SetWorkflowParam

此接口用来设置workflow运行时的参数模版。以下代码展示如何设置指定workflow的参数模版：

set_workflow_param_result = workflow.set_workflow_param('exec_worklow_param_file_path', 'workflow_name', workflow_version)

提示：

需要提供一个yaml格式的parameter_file配置文件，记录该workflow的参数配置，可通过GetExecutableWorkflow操作获取。

可参照 genedock-official-python-sdk/examples/task_active.yml。

DeleteWorkflow

以下代码展示如何删除指定workflow：

# 必须指定版本号
delete_workflow_result = workflow.delete_workflow('workflow_name', workflow_version)

ListWorkflow

有时候可能需要查看一个账号下的所有工作流(不一定有运行权限)。以下代码展示如何列举某账号下的workflow：

list_workflow_result = workflow.list_workflows()
# 查看workflow列表详情
print list_workflow_result.workflows
# 列出的workflow的数量
print list_workflow_result.count

ListExecutableWorkflow

此接口可以列出所有可以运行的工作流。以下代码展示如何列举某账号下可运行的workflow：

list_excutable_workflow_result = workflow.list_exc_workflows()
# 查看workflow列表详情
print list_excutable_workflow_result.workflows
# 列出的workflow数量
print list_excutable_workflow_result.count

Task操作

GetTask

投递了一个新的task后，有时候需要看一下task的状态等信息。以下的代码展示如何获取一个task的meta信息：

# task_id可以从list_task中获取，也可以从GeneDock网站页面的任务详情中获取
task_get_result = task.get_task('task_id')
# 获取该task的详情
print task_get_result.response.text

ActivateWorkflow

以下的代码展示如何从workflow生成一个task：

# 1. 首先需要编写改任务的配置文件parameter_file，记录本次务的详细配置，所需要的输入文件和参数等
# 2. 需要获取到该任务所用的workflow名称workflow_name和版本号workflow_version
active_workflow_result = task.active_workflow('parameter_file', 'workflow_name', workflow_version)
# 3. 如果想要运行其他用户授权的工作流，必须加上workflow_owner参数
active_workflow_result = task.active_workflow('parameter_file', 'workflow_name', workflow_version, 'workflow_owner')
# 任务成功启动后的task_id
print active_workflow_result.task_id
# 任务成功启动后的task_name
print active_workflow_result.task_name

提示：

可按照 genedock-official-python-sdk/examples/task_active.yml 为例

ListTask

以下的代码展示如何列举某账号下的task：

# 列举账号下的tasks
1) 默认列出该账号下7天内（即当前时刻7*24小时内）提交的tasks
task_list_result = task.list_tasks()
2) 获取指定日期的tasks（需增加查询开始时间点和查询结束时间点等请求参数）
task_list_result = task.list_tasks(params={'size': size_num, 'from': from_date, 'to': to_date})
# 获取查询时间段内tasks的详细内容
print task_list_result.task_list
# 该次获取到的tasks的数量（与请求参数size相关，默认值500）
print task_list_result.count
# 该账户在查询时间段内所有的tasks数量
print task_list_result.total

提示：

当想列出指定账号下提交的所有任务（即从账号创建日期开始到现在）时，可以：

• size：默认值500，设置成一个比较大的整数，比如：10000000
• from：默认值当前时刻 7*24小时前，设置成一个早与账号创建的日期，比如：2014年9月1日00:00:00（需要转换为unix时间戳格式：1409500800）
• to：默认值为当前时刻，也可以自己定义（unix时间戳格式）

例如：task.list_tasks(params={‘size’: 10000000, ‘from’: 1409500800, ‘to’: XXX})

ListTask还提供了其他请求参数，可参考API-Reference中关于ListTask的说明。

DeleteTask

以下的代码展示如何删除一个task：

delete_task_result = task.delete_task('task_id')

提示：

只能删除状态为success、failed或者compiled的任务。

StopTask

以下的代码展示如何停止一个task：

stop_task_result = task.stop_task('task_id')
# 查看停止该task的详情
print stop_task_result.response.text

提示：

只能停止状态为running的任务。

ListJob

以下的代码展示如何列举一个task下所有job的信息：

# 获取某个task下的jobs以便于查看该task的运行进度
job_get_result = task.get_jobs('task_id')
# 查看所有jobs详情
print job_get_result.jobs
# 获取所有jobs的数量
print job_get_result.count

GetJobCmd

以下的代码展示如何获取某个job所运行的command：

get_job_cmd_result = task.get_job_cmd('job_id')
# 查看指定job的cmd
print get_job_cmd_result.cmd

提示：

通过ListJob列举指定task下所有job的信息，获取某个job的job id。

只能获取对相关工具有编辑权限（即自己账号下创建的工具）的job的command。

Data操作

ArchiveData

以下代码展示如何归档指定文件:

archive_data_result = data.archive_data('data_path')

提示：

暂时不支持归档目录。

归档过程中会根据文件的大小和服务器负载会持续几分钟和几小时不等。

RestoreData

以下代码展示如何恢复指定文件:

restore_data_result = data.restore_data('data_path')

提示:

服务端在接到用户的恢复请求以后，会开始恢复文件，恢复的过程会持续0到4个小时不等。

恢复完成后，文件处于已恢复的状态，此状态默认保持1天。

用户可以对restored状态的数据再次执行恢复操作，以延长文件的restored状态。

每请求一次延长1天，最多延长至7天。

批量获取data_path

以下代码展示如何从一个指定的目录获取它所有的文件，包括它所有子目录下的文件。

import json
import gdpy
import requests
# 以北京域为例
url = "https://cn-beijing-api.genedock.com/accounts/username/projects/default/data/"
# 秘钥
auth = gdpy.auth.GeneDockAuth("Access Id", "Access Key")
# 指定test/目录下的所有文件
file_path = "test/"
# 存储所有文件的路径
file_names = []
list_file_API(url, file_path, auth, file_names)

def list_file_API(url, file_path, auth, file_names):
    resp = requests.get("{0}{1}".format(url, file_path), auth=auth)
    resp_json = json.loads(resp.text)
    for file_info in resp_json[u'data_list']:
        if file_info['type'] == 'file' and file_info['status'] == 'available':
            path = '{}{}'.format(file_path, file_info['name'])
            file_names.append(path)
        elif file_info['type'] == 'directory':
            path = '{}{}'.format(file_path, file_info['name'])
            list_file_API(url, path, auth, file_names)

提示：

file_path是目录名。

指定目录下所有的文件路径放在file_names变量中。

异常处理

调用gdpy类的相关接口时，如果抛出异常，则表明操作失败，否则操作成功。抛出异常时，方法返回的数据无效。GeneDock Offical Python SDK包含两类异常，一类是服务器端异常ServerError，另一类是请求异常RequestError，它们均继承自Exception。

异常处理示例

try:
    tr = task.get_task('jasfdjkasf')
except gdpy.exceptions.ServerError as se:
    print se.status
    print se.request_id
    print se.error_message
    print se.code
    print se.error_message_chs

RequestError

RequestError表示客户端尝试向GeneDock发送请求以及数据传输时遇到的异常。例如，当发送请求时网络连接不可用时，则会抛出 RequestError。

ServerError

ServerError指服务器端错误，它来自于对服务器错误信息的解析，包含GeneDock会返回给用户相应的错误码和错误信息，便于用户定位问题，并做出适当的处理。

ServerError通常包含以下错误信息：

• status: 返回状态
• code: GeneDock返回给用户的错误码。
• error_message: GeneDock提供的详细错误信息。
• requestId: 用于唯一标识该请求的UUID；当您无法解决问题时，可以凭这个RequestId来请求GeneDock开发工程师的帮助。
• error_message_chs: GeneDock提供的详细错误中文信息。